Programming With QuickTime VR

Example: Getting the Name of a Node

You can use standard QuickTime atom container functions to retrieve the information in a node header atom. For example, the MyGetNodeName function defined in Listing 4-1 returns the name of a node, given its node ID.

Listing 1 Getting a node's name



 
OSErr MyGetNodeName (QTVRInstance theInstance, UInt32 theNodeID, 

                                                                StringPtr theStringPtr)

{

    OSErr                   theErr = noErr;

    QTAtomContainer         theNodeInfo;

    VRNodeHeaderAtomPtr     theNodeHeader;

    QTAtom                  theNodeHeaderAtom = 0;

    

    //Get the node information atom container.

    theErr = QTVRGetNodeInfo(theInstance, theNodeID, &theNodeInfo);

    

    //Get the node header atom. 

    if (!theErr)

        theNodeHeaderAtom = QTFindChildByID(theNodeInfo, kParentAtomIsContainer, 

                                                    kQTVRNodeHeaderAtomType, 1, nil);

    if (theNodeHeaderAtom != 0) {

        QTLockContainer(theNodeInfo);

        

        //Get a pointer to the node header atom data.

        theErr = QTGetAtomDataPtr(theNodeInfo, theNodeHeaderAtom, nil, 

                                                            (Ptr *)&theNodeHeader);

        //See if there is a name atom.

        if (!theErr && theNodeHeader->nameAtomID != 0) {

            QTAtom theNameAtom;

            theNameAtom = QTFindChildByID(theNodeInfo, kParentAtomIsContainer, 

                                kQTVRStringAtomType, theNodeHeader->nameAtomID, nil);

            if (theNameAtom != 0) {

                VRStringAtomPtr theStringAtomPtr;

                

                //Get a pointer to the name atom data; copy it into the string.

                theErr = QTGetAtomDataPtr(theNodeInfo, theNameAtom, nil, 

                                                            (Ptr *)&theStringAtomPtr);

                if (!theErr) {

                    short theLen = theStringAtomPtr->stringLength;

                    if (theLen > 255)

                        theLen = 255;

                    BlockMove(theStringAtomPtr->string, &theStringPtr[1], theLen);

                    theStringPtr[0] = theLen;

                }

            }

        }

        QTUnlockContainer(theNodeInfo);

    }



    QTDisposeAtomContainer(theNodeInfo);

    return(theErr);

}

The MyGetNodeName function defined in Listing 4-1 retrieves the node information atom container (by calling QTVRGetNodeInfo ) and then looks inside that container for the node header atom with atom ID 1. If it finds one, it locks the container and then gets a pointer to the node header atom data. The desired information, the node name, is contained in the string atom whose atom ID is specified by the nameAtomID field of the node header structure. Accordingly, the MyGetNodeName function then calls QTFindChildByID once again to find that string atom. If the string atom is found, MyGetNodeName calls QTGetAtomDataPtr to get a pointer to the string atom data. Finally, MyGetNodeName copies the string data into the appropriate location and cleans up after itself before returning.